%% Estimate Panel VAR
% by Jaromir Benes
% 
% Estimate a panel VAR combining the data for all three countries with
% fixed effect (i.e. dummy constats for each country).

%% Clear Workspace
%
% Clear workspace, close all figure windows, move to the top of the command
% screen, and check the IRIS version.

clear;
close all;
home;
irisrequired 20130401;

%% Load Input Data
%
% Load the struct `d` with three country sub-databases from a binary file
% prepared in `read_data`. You must run `read_data` at least once before
% this file to create the necessary mat file.

load read_data.mat d;

%% Estimate Panel VAR
%
% There are two main differences in how to to set up and estimate a panel
% VAR. First, the VAR object is created with the list of variables (here:
% `infl`, `gap`, `int`, `dex`), and the names of groups of data (here:
% shorts for countries `Au`, `Ca`, `No`) passed in through the option
% `'groups='` <?constructor?>. Second, the input data must be passed as a
% struct with subdatabases for each group of data (here: countries), and
% the subdatabases must be named the same as the groups (here: `Au`, `Ca`,
% `No`).
%
% By default, panel VARs are estimated with fixed effects: a constant dummy
% variable is included for each of the groups. The fixed effect can be
% removed by setting the option `'fixedEffect='` to `false`.
%
% When estimating a panel VAR, the individual groups can be given unequal
% weights (for instance, to reflect the size of each country) using the
% option `'groupWeights='` <?groupweights?>. Here, all groups (all
% countries) are given the same weight; this is also the default behaviour
% and the option can be omitted in that case.

p = 2;
estrange = qq(1997,1) : qq(2012,2);

vp = VAR({'infl','gap','int','dex'}, ...
    'groups=',{'Au','Ca','No'}); %?constructor?

[vp,dvp] = estimate(vp,d,estrange, ...
    'order=',p','groupWeights=',[1,1,1]) %#ok<NOPTS> %?groupweights?

%% Structure of Panel VAR Object
%
% Panel VAR objects are very similar to plain VAR objects. The only
% difference is that they have constant terms estimated individually for
% each of the groups (using group-specific dummy constants), and hence each
% group has a different unconditional mean.
%
% The other parameters, i.e. the polynomial in the lag operators as well as
% the covariance matrix of residuals, are shared across all groups.
%
% * <?AL?> Parameters in the $A(L)$ polynomial.
% * <?Omega?> Covariance matrix of residuals
% * <?K?> Constant vectors for individual groups (columnwise)
% * <?uncmean?> Unconditional means of individual groups (columnwise)

A = get(vp,'A*') %#ok<NOPTS> %?AL?

Omg = get(vp,'Omega') %#ok<NOPTS> %?Omega? 

K = get(vp,'K') %#ok<NOPTS> %?K?

unc_mean = mean(vp) %#ok<NOPTS> %?uncmean?

%% Save Estimated Panel VARs
%
% Save the estimated individual VARs, along with the output data, to a
% binary file `estimate_panel.mat` for future use.

save estimate_panel_var.mat vp dvp;

%% Help on IRIS Functions Used in This M-file
%
% Use either `help` to display help in the command window, or `idoc`
% to display help in an HTML browser window.
%
%    help dates/qq
%    help VAR/Contents
%    help VAR/VAR
%    help VAR/estimate
%    help VAR/get
%    help VAR/mean
